<html>
<head><meta charset="utf-8"><title>WG-comments? · t-compiler · Zulip Chat Archive</title></head>
<h2>Stream: <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/index.html">t-compiler</a></h2>
<h3>Topic: <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html">WG-comments?</a></h3>

<hr>

<base href="https://rust-lang.zulipchat.com">

<head><link href="https://rust-lang.github.io/zulip_archive/style.css" rel="stylesheet"></head>

<a name="199832594"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199832594" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> mark-i-m <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199832594">(Jun 05 2020 at 03:21)</a>:</h4>
<p>Hi, I'm wondering what people think of this idea: start a WG-comments whose only task is to write doc comments for the compiler. The idea is that thorough doc comments would make it way easier to jump into the compiler as a beginner, whereas currently a lot of the compiler is undocumented and mysterious, and many contributors report feeling overwhelmed/not knowing where to start.</p>



<a name="199832606"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199832606" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> mark-i-m <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199832606">(Jun 05 2020 at 03:21)</a>:</h4>
<p>Writing comments is a task that can be done incrementally with little chunks of time and doesn't require any setup to build the compiler.</p>



<a name="199832653"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199832653" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> mark-i-m <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199832653">(Jun 05 2020 at 03:22)</a>:</h4>
<p>And at the same time, learning something well enough to write comments may be a good intro for someone to contribute further.</p>



<a name="199832658"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199832658" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> mark-i-m <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199832658">(Jun 05 2020 at 03:22)</a>:</h4>
<p>Thoughts?</p>



<a name="199833409"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199833409" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Noah Lev <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199833409">(Jun 05 2020 at 03:44)</a>:</h4>
<p>I've thought about trying to write some docs, but I'm pretty new and so don't feel confident enough in my knowledge of how things work</p>



<a name="199833491"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199833491" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Noah Lev <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199833491">(Jun 05 2020 at 03:47)</a>:</h4>
<p>I think it <em>would</em> be a good intro to better understanding, but I think there's a bit of a chicken-and-egg problem since you need to understand stuff to write docs, but you need docs to understand stuff.</p>



<a name="199839354"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199839354" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Félix Fischer <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199839354">(Jun 05 2020 at 06:18)</a>:</h4>
<p>The thing is</p>



<a name="199839361"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199839361" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Félix Fischer <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199839361">(Jun 05 2020 at 06:18)</a>:</h4>
<p>That more than a chicken and egg problem, we have a lot of "oral tradition", if you wish</p>



<a name="199839374"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199839374" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Félix Fischer <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199839374">(Jun 05 2020 at 06:19)</a>:</h4>
<p>Lots of the relevant knowledge about the compiler is in the people that work and have worked on it</p>



<a name="199839380"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199839380" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Félix Fischer <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199839380">(Jun 05 2020 at 06:19)</a>:</h4>
<p>And it's transmitted by asking questions and stuff</p>



<a name="199839434"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199839434" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Félix Fischer <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199839434">(Jun 05 2020 at 06:20)</a>:</h4>
<p>But I think that you're right, <span class="user-mention" data-user-id="307537">@Camelid</span>, in the sense that one needs to understand how things work in order to write about how they work :3</p>



<a name="199839449"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199839449" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Félix Fischer <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199839449">(Jun 05 2020 at 06:21)</a>:</h4>
<p><span class="user-mention" data-user-id="198054">@mark-i-m</span> this is so my jam. I wanna write doc comments all day long</p>



<a name="199839460"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199839460" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Félix Fischer <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199839460">(Jun 05 2020 at 06:21)</a>:</h4>
<p>If this WG gets made, please do add me</p>



<a name="199839521"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199839521" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Félix Fischer <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199839521">(Jun 05 2020 at 06:23)</a>:</h4>
<p>This is a bit of a pet peeve that I have with the current documentation</p>



<a name="199839522"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199839522" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Félix Fischer <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199839522">(Jun 05 2020 at 06:23)</a>:</h4>
<p>I mean don't get me wrong; whatever is there has helped me a lot. But there's so much, so so much missing.</p>



<a name="199839575"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199839575" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Félix Fischer <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199839575">(Jun 05 2020 at 06:24)</a>:</h4>
<p>At least around the miri and mir-opt parts. I haven't worked much with the rest of the compiler yet x3</p>



<a name="199846647"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199846647" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Nathan Corbyn <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199846647">(Jun 05 2020 at 08:15)</a>:</h4>
<p>I think this is a great idea - I'd be more than happy to help if you got this going</p>



<a name="199846757"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199846757" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> detrumi <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199846757">(Jun 05 2020 at 08:16)</a>:</h4>
<p>Having some guidance on how to go about writing doc comments (and improving the workflow around it) would be helpful</p>



<a name="199884894"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199884894" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Tshepang Lekhonkhobe <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199884894">(Jun 05 2020 at 14:33)</a>:</h4>
<p>good idea... rustc comments don't get lots of love, and since this is internal stuff, I think perhaps all of them should be exposed to rustdoc</p>



<a name="199884917"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199884917" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Tshepang Lekhonkhobe <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199884917">(Jun 05 2020 at 14:33)</a>:</h4>
<p>also, s/comments/rustc-comments</p>



<a name="199886355"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199886355" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> mark-i-m <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199886355">(Jun 05 2020 at 14:44)</a>:</h4>
<p>Cool, so this is helpful feedback.</p>



<a name="199886685"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199886685" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> mark-i-m <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199886685">(Jun 05 2020 at 14:46)</a>:</h4>
<p>Here is how I've done this in the past when approaching a large unknown piece of code: I try to find what looks like the entry point of some code that I know the high-level purpose of (i.e. "I know this code parses macros somehow"). Then, I just start reading that code and leaving (normal) comments for myself as I read. Eventually, I get a good enough picture of what</p>



<a name="199886721"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199886721" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> mark-i-m <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199886721">(Jun 05 2020 at 14:46)</a>:</h4>
<p>...'s going on to write reasonable doc comments</p>



<a name="199886848"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199886848" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> mark-i-m <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199886848">(Jun 05 2020 at 14:47)</a>:</h4>
<p>I think if we do such a WG, though, we should liberally take advantage of the compiler team to find out what the high-level design of something is, and then we can figure out the details</p>



<a name="199905711"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199905711" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> mark-i-m <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199905711">(Jun 05 2020 at 16:59)</a>:</h4>
<p>Oh, wow, I just noticed that there is a <code>submodules = false</code> config in <code>config.toml</code></p>



<a name="199905813"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199905813" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> mark-i-m <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199905813">(Jun 05 2020 at 17:00)</a>:</h4>
<p>sorry, wrong topic</p>



<a name="199933620"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/WG-comments%3F/near/199933620" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/WG-comments.3F.html#199933620">(Jun 05 2020 at 21:00)</a>:</h4>
<p>I'm in favor of the plan</p>



<hr><p>Last updated: Aug 07 2021 at 22:04 UTC</p>
</html>